From aaab7d15fa0f7774a31b346884d8c463118abd62 Mon Sep 17 00:00:00 2001
From: Jonathan Lebon <jonathan@jlebon.com>
Date: Thu, 11 Sep 2025 15:28:34 -0400
Subject: [PATCH] man/ostree-state-overlay: drop experimental but link to bootc
 docs

This has baked for long enough now so drop the experimental flag. But do
explain that symlinks are preferred and link to the bootc docs.
---
 man/ostree-state-overlay@.service.xml | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/man/ostree-state-overlay@.service.xml b/man/ostree-state-overlay@.service.xml
index 7f24f253..f670198a 100644
--- a/man/ostree-state-overlay@.service.xml
+++ b/man/ostree-state-overlay@.service.xml
@@ -44,15 +44,14 @@ Boston, MA 02111-1307, USA.
   </refsynopsisdiv>
 
   <refsect1>
-    <title>Experimental</title>
+    <title>Dealing with /opt</title>
     <para>
-      <emphasis role="bold">Note this feature is currently considered
-      experimental.</emphasis> It may not work correctly and some of its
-      semantics may be subject to change. Positive or negative feedback are both
-      welcome and may be provided at
-      <ulink url="https://github.com/ostreedev/ostree/discussions"/>. If using
-      the feature via rpm-ostree, feedback may also be provided at
-      <ulink url="https://github.com/coreos/rpm-ostree/issues/233"/>.
+      <emphasis role="bold">Note:</emphasis> In general, the preference for
+      handling <filename>/opt</filename> software is to use symbolic links for
+      just the parts that need to be mutable to some place in
+      <filename>/var</filename> that can be created e.g. by a
+      <literal>tmpfiles.d</literal> dropin. For more information, see
+      <ulink url="https://bootc-dev.github.io/bootc/building/guidance.html#handling-read-only-vs-writable-locations"/>.
     </para>
   </refsect1>
 
-- 
2.30.2